클로드 코드 완벽 가이드 — 25장 ccusage 딥다이브 학습 노트

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호) | 참고: https://github.com/codefactory-co

25장에서 다루는 내용

• ccusage 소개와 필요성 — 클로드 코드 토큰 사용량을 분석하고 시각화하는 오픈소스 도구
• ccusage 설치하기 — bun 런타임 설치 후 bunx로 ccusage 실행 환경 구성
• ccusage 핵심 기능 5가지 — daily, monthly, session, blocks, mcp 기능 활용법

전체 흐름도

[ccusage 필요성]              [설치]                    [사용하기]
    |                          |                          |
    v                          v                          v
+---------------------+  +-------------------+  +---------------------------+
| 클로드 코드는 토큰   |  | 1. bun 설치       |  | daily   - 일별 통계       |
| 사용량/비용을 직접   |  |  macOS: curl      |  | monthly - 월별 통계       |
| 보여주지 않음        |  |  Windows: PS      |  | session - 세션별 통계     |
|                     |  |                   |  | blocks  - 5시간 블록별    |
| 5시간 블록 제한 걸려 |  | 2. bunx --help    |  | mcp     - MCP 서버 연동   |
| 야 뒤늦게 알게 됨   |  |    으로 확인      |  |                           |
|                     |  |                   |  | --since / --until 필터    |
| Sonnet/Opus 혼용    |  | 3. bunx ccusage   |  | 라이브 블록 모니터링      |
| 전략 필요           |  |    <명령> 실행    |  | .mcp.json MCP 연동        |
+---------------------+  +-------------------+  +---------------------------+

핵심 키워드

선수 지식 체크리스트

• [ ] 터미널(CLI) 기본 사용법을 알고 있다
• [ ] 클로드 코드가 무엇인지, 기본적인 사용법을 알고 있다
• [ ] 토큰 개념과 AI 모델 요금 체계(입력/출력 토큰 과금)를 이해하고 있다
• [ ] npm/bunx 같은 패키지 매니저의 기본 개념을 알고 있다
• [ ] MCP(Model Context Protocol)의 기본 개념을 알고 있다 (MCP 연동 시)

25-1 ccusage란? — 왜 필요한가

한 줄 요약

클로드 코드는 토큰 사용량과 비용을 직접 보여주지 않기 때문에, ccusage를 설치하면 일별/월별/세션별 사용 통계와 실시간 모니터링이 가능하다.

쉬운 설명 — 핸드폰 데이터 잔량 앱

핸드폰 데이터를 쓸 때, 통신사 앱에서 "이번 달 얼마나 썼고 얼마 남았는지" 확인하는 것처럼, ccusage는 클로드 코드의 "토큰 데이터 잔량"을 보여주는 앱이다. 데이터 다 떨어지기 전에 미리 확인할 수 있으면 당연히 좋다!

클로드 코드의 사용량 관리 문제

❌ 클로드 코드 기본 상태:
- 토큰 사용량 비공개
- 세션 블록 정보 비공개
- 열심히 코딩하다 갑자기 "5시간 후에 사용 가능" 메시지 등장
- Sonnet vs Opus 어떤 모델을 얼마나 썼는지 알 수 없음

✅ ccusage 설치 후:
- 일별/월별 토큰 사용량 + 비용 확인
- 세션별/블록별 상세 분석
- 라이브 모니터링으로 남은 시간/토큰 예측
- 모델별(Sonnet/Opus) 사용량 구분

핵심 체크포인트

• [ ] 클로드 코드는 토큰 사용량을 직접 공개하지 않는다
• [ ] Pro 플랜이나 API 요금제 사용 시 비용 관리가 특히 중요하다
• [ ] ccusage는 오픈소스 도구로, 아직 초기이지만 충분히 실용적이다

25-2 ccusage 설치하기

한 줄 요약

bun 런타임을 먼저 설치한 후, bunx 명령어로 ccusage를 별도 설치 없이 바로 실행할 수 있다.

쉬운 설명 — 앱스토어에서 앱 받기

bun은 일종의 "앱스토어"이고, bunx는 "설치하지 않고 바로 실행하기" 버튼이다. 앱스토어(bun)를 먼저 깔고, 그 안에서 ccusage를 바로 실행(bunx)하면 된다.

설치 절차

[1단계: bun 설치]
│
├── macOS:
│   curl -fsSL https://bun.com/install | bash
│
├── Windows:
│   powershell -c "irm bun.sh/install.ps1|iex"
│
└── 설치 확인:
    bunx --help
    → Usage: bunx [flags] <package>... 출력되면 성공

[2단계: ccusage 실행]
│
└── bunx ccusage <명령어>
    → 로컬 설치 불필요, 항상 최신 버전 자동 실행

실무 예제

# macOS에서 bun 설치
curl -fsSL https://bun.com/install | bash

# Windows에서 bun 설치
powershell -c "irm bun.sh/install.ps1|iex"

# 설치 확인
bunx --help

# ccusage 바로 실행 (별도 설치 불필요)
bunx ccusage daily

핵심 체크포인트

• [ ] bun은 JavaScript/TypeScript 런타임으로, ccusage 실행에 필요한 기반 도구다
• [ ] bunx는 패키지를 로컬에 설치하지 않고 바로 실행하는 명령어다
• [ ] macOS와 Windows의 설치 명령어가 다르므로 OS에 맞는 명령어를 사용한다
• [ ] bunx --help 출력이 정상이면 설치 성공이다

25-3 ccusage 사용하기 — daily (일별 통계)

한 줄 요약

bunx ccusage daily는 날짜별로 사용한 모델, 입력/출력 토큰, 비용을 한눈에 보여준다.

쉬운 설명 — 가계부 일별 지출 내역

매일 얼마를 썼는지 적는 가계부처럼, daily 명령은 "오늘은 Sonnet에 $12, 어제는 Opus에 $43" 이런 식으로 날짜별 AI 사용 비용을 정리해준다.

실무 예제

# 전체 일별 통계 조회
bunx ccusage daily

# 출력 예시:
# Date       Models           Input     Output    Cost (USD)
# 2025-07-20 - sonnet-4       4,419     108,474   $12.37
# 2025-07-21 - sonnet-4       40,397    234,335   $36.64
# 2025-07-22 - opus-4         18,395    168,396   $43.82
#              - sonnet-4
# Total                       982,901   14,984,662 $3807.68

출력 항목 설명

핵심 체크포인트

• [ ] daily는 날짜별 토큰 사용량과 예상 비용을 보여준다
• [ ] 하루에 여러 모델을 사용했으면 모델별로 구분 표시된다
• [ ] 마지막 줄의 Total은 전체 기간의 누적 합계다

25-4 ccusage 사용하기 — monthly (월별 통계)

한 줄 요약

bunx ccusage monthly는 월별로 토큰 사용량과 비용을 정리해 장기적인 사용 추이를 파악할 수 있다.

쉬운 설명 — 월별 카드 명세서

매달 오는 카드 명세서처럼, monthly 명령은 "6월에 $1,084, 7월에 $2,722" 이런 식으로 월 단위 AI 사용 비용을 정리해준다.

실무 예제

# 월별 통계 조회
bunx ccusage monthly

# 출력 예시:
# Month    Models             Input     Output       Cost (USD)
# 2025-06  - opus-4           11,830    538,471      $1084.79
#            - sonnet-4
# 2025-07  - opus-4           971,071   14,446,191   $2722.89
#            - sonnet-4
# Total                       982,901   14,984,662   $3807.68

핵심 체크포인트

• [ ] monthly는 월 단위로 토큰 사용량과 비용을 집계한다
• [ ] 월별 모델 사용 비율 변화를 통해 비용 최적화 전략을 세울 수 있다

25-5 ccusage 사용하기 — session (세션별 통계)

한 줄 요약

bunx ccusage session은 프로젝트/대화 세션별로 토큰 사용량을 정리하여, 어떤 작업에 토큰을 많이 썼는지 파악할 수 있다.

쉬운 설명 — 프로젝트별 예산 사용 현황

회사에서 프로젝트별로 예산을 나눠 관리하는 것처럼, session 명령은 "A 프로젝트에 $3.78, B 프로젝트에 $0.75" 이런 식으로 프로젝트(세션)별 비용을 보여준다.

실무 예제

# 세션별 통계 조회
bunx ccusage session

# 출력 예시:
# Session          Models      Input    Output   Cost    Date
# proj-2           - sonnet-4  46       9,463    $0.76   2025-...
# improvement-18.. - sonnet-4  34,613   3,811    $0.89   2025-...
# mcp-test         - sonnet-4  227      35,023   $3.78   2025-...
# Desktop-asymme.. - sonnet-4  491      20,776   $3.61   2025-...

세션 인식 규칙

하나의 대화일 = 하나의 세션
  → 같은 프로젝트 폴더에서 대화

워크트리 생성 = 새로운 세션
  → 워크트리로 새 폴더를 만들면 별도 세션으로 인식

핵심 체크포인트

• [ ] session은 프로젝트(대화 세션) 기준으로 사용량을 정리한다
• [ ] 워크트리를 사용해 새 폴더를 만들면 새로운 세션으로 인식된다
• [ ] 어떤 프로젝트에 토큰을 많이 썼는지 비교할 수 있다

25-6 ccusage 사용하기 — blocks (블록별 통계)

한 줄 요약

bunx ccusage blocks는 클로드 코드의 5시간 블록 단위로 사용량을 정리하며, 현재 활성 블록도 보여준다.

쉬운 설명 — 뷔페 타임 슬롯

뷔페에서 "1차 11시~2시, 2차 2시~5시"처럼 시간대별로 나뉘는 것과 같다. 클로드 코드도 5시간 단위로 "뷔페 시간"이 나뉘고, blocks는 각 시간대에 얼마나 먹었는지(토큰을 썼는지) 보여준다.

실무 예제

# 블록별 통계 조회
bunx ccusage blocks

# 출력 예시:
# Time                          Status      Models      Output    Cost
# 07/23, 09:00 PM (1h22m)                   - sonnet-4  8,185,4.. $3.61
# 07/24, 03:22 AM (9h gap)      (inactive)  -           -         -
# 07/24, 11:00 AM (0h58m/4h2m)  ACTIVE      - sonnet-4  61,564    $0.23

블록 상태 설명

핵심 체크포인트

• [ ] blocks는 5시간 윈도우(블록) 단위로 사용량을 보여준다
• [ ] ACTIVE 블록에서 남은 시간(예: 4h2m)을 확인할 수 있다
• [ ] inactive 구간은 클로드 코드를 사용하지 않은 공백 시간이다

25-7 since/until 필터와 라이브 블록 모니터링

한 줄 요약

--since와 --until 플래그로 기간을 필터링하고, 라이브 블록 기능으로 현재 세션의 토큰 소비를 실시간 모니터링할 수 있다.

쉬운 설명 — 은행 앱 기간 조회 + 실시간 잔액 알림

은행 앱에서 "7월 22일~23일" 거래만 조회하는 것이 since/until이고, 계좌 잔고가 실시간으로 줄어드는 걸 보는 것이 라이브 블록 모니터링이다.

기간 필터 사용법

# 2025년 7월 22일부터 7월 23일까지의 일별 통계
bunx ccusage daily --since 20250722 --until 20250723

# 출력 예시:
# Date       Models              Input    Output    Cost (USD)
# 2025-07-22 - opus-4            18,395   168,396   $43.82
#              - sonnet-4
# 2025-07-23 - opus-4            52,448   96,218    $35.72
#              - sonnet-4
# Total                          70,843   264,614   $79.54

라이브 블록 모니터링

┌──────────────────────────────────────────────────┐
│        CLAUDE CODE - LIVE TOKEN USAGE MONITOR    │
│                                                  │
│  ● SESSION  [████████░░░░░░░░]  25.1%            │
│    Started: 11:00:00 AM  Remaining: 3h (04:00 PM)│
│                                                  │
│  🔥 USAGE  [██░░░░░░░░░░░░░░]  (16 tokens)      │
│    Tokens: 16 (Burn Rate: N/A)       Cost: $0.23 │
│                                                  │
│  ⚙ Models: sonnet-4                              │
│    ↻ Refreshing every 1s  ■ Press Ctrl+C to stop │
└──────────────────────────────────────────────────┘

라이브 모니터링 주요 정보

핵심 체크포인트

• [ ] --since YYYYMMDD --until YYYYMMDD 형식으로 기간 필터링한다
• [ ] since/until은 daily, monthly, session, blocks 모든 기능과 함께 사용 가능하다
• [ ] 라이브 블록 모니터링은 1초마다 자동 갱신되며, Ctrl+C로 종료한다
• [ ] 남은 세션 시간과 토큰 소비 속도를 실시간으로 확인할 수 있다

25-8 ccusage를 MCP 서버로 사용하기

한 줄 요약

bunx ccusage mcp로 ccusage를 MCP 서버로 실행하고, 프로젝트의 .mcp.json에 등록하면 클로드 코드 안에서 직접 사용량을 조회할 수 있다.

쉬운 설명 — 대시보드를 앱 안에 내장하기

지금까지는 별도의 터미널 창에서 ccusage를 실행했다면, MCP 연동은 클로드 코드 앱 안에 "사용량 대시보드"를 직접 내장하는 것과 같다. 앱을 떠나지 않고 바로 확인!

MCP 서버 설정 방법

# 1. ccusage MCP 서버 실행 (터미널에서)
bunx ccusage mcp
# → 커서가 멈추면 MCP 서버가 정상 실행된 것

# 2. 프로젝트 루트의 .mcp.json에 추가
{
  "mcpServers": {
    "ccusage": {
      "command": "bunx",
      "args": ["ccusage", "mcp"]
    }
  }
}

MCP 연동 후 활용

클로드 코드 안에서:
  "오늘 토큰 얼마나 썼어?"
  → ccusage MCP가 자동으로 daily 데이터 조회하여 응답

  "이번 달 비용 얼마야?"
  → ccusage MCP가 monthly 데이터 조회하여 응답

핵심 체크포인트

• [ ] bunx ccusage mcp로 ccusage를 MCP 서버로 실행할 수 있다
• [ ] .mcp.json 파일에 ccusage MCP를 등록하면 프로젝트에서 자동 연동된다
• [ ] MCP 연동 후에는 클로드 코드 대화 중에 직접 사용량을 질문할 수 있다

연습문제

문제 1 (기본)

ccusage의 5가지 핵심 기능(daily, monthly, session, blocks, mcp)을 각각 한 문장으로 설명하시오.

문제 2 (중급)

2025년 8월 1일부터 8월 15일까지의 일별 사용량만 조회하는 ccusage 명령어를 작성하시오. 또한 해당 명령어에서 since와 until의 날짜 형식을 설명하시오.

bunx ccusage daily --since 20250801 --until 20250815

문제 3 (심화)

ccusage의 session 기능에서 워크트리를 생성하면 새로운 세션으로 인식되는 이유를 설명하고, 이를 활용하여 프로젝트별 비용을 분리 추적하는 전략을 제시하시오.

부록 A — 용어 사전

부록 B — 비교표

ccusage 기능 비교

bun 설치 명령어 비교

ccusage vs 수동 관리 비교

부록 C — 참고 자료